'\" te
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH INTRSTAT 8 "Dec 10, 2017"
.SH NAME
intrstat \- report interrupt statistics
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/intrstat\fR [\fB-c\fR \fIcpulist\fR | \fB-C\fR \fIprocessor_set_id\fR] [\fB-T\fR u | d ]
     [\fB-x\fR \fIopt\fR[=\fIval\fR]] [\fIinterval\fR [\fIcount\fR]]
.fi

.SH DESCRIPTION
.LP
The \fBintrstat\fR utility gathers and displays run-time interrupt statistics.
The output is a table of device names and CPU IDs, where each row of the table
denotes a device, and each column of the table denotes a CPU. Each cell in the
table contains both the raw number of interrupts for the given device on the
given CPU, and the percentage of absolute time spent in that device's interrupt
handler on that CPU.
.sp
.LP
The device name is given in the form of
\fB{\fR\fIname\fR}\fI#\fR\fB{\fR\fIinstance\fR\fB}\fR. The name is the
normalized driver name, and typically corresponds to the name of the module
implementing the driver. See \fBddi_driver_name\fR(9F). Many Sun-delivered
drivers have their own manual pages. See \fBIntro\fR(4).
.sp
.LP
If standard output is a terminal, the table contains as many columns of data as
can fit within the terminal width. If standard output is not a terminal, the
table contains at most four columns of data. By default, data is gathered and
displayed for all CPUs. If the data cannot fit in a single table, it is printed
across multiple tables. The set of CPUs for which data is displayed can be
optionally specified with the \fB-c\fR or \fB-C\fR option.
.sp
.LP
By default, \fBintrstat\fR displays data once per second and runs indefinitely.
Both of these behaviors can be optionally controlled with the interval and
count parameters, respectively. See \fBOPERANDS\fR.
.sp
.LP
Because \fBintrstat\fR uses dynamic discovery, it reports only on devices that
raise interrupts while the command is running. Any devices that  are silent
while \fBintrstat\fR is running are not displayed.
.sp
.LP
\fBintrstat\fR induces a small system-wide performance degradation. As a
result, only the super-user can run \fBintrstat\fR by default. The
\fIDynamic Tracing Guide\fR explains how administrators can grant privileges to
other users to permit them to run \fBintrstat\fR.
.SH OPTIONS
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-c\fR \fIcpulist\fR\fR
.ad
.sp .6
.RS 4n
Displays data for the CPUs specified by \fIcpulist\fR.
.sp
\fIcpulist\fR can be a single processor ID (for example, \fB4\fR), a range of
processor IDs (for example, \fB4-6\fR), or a comma separated list of processor
IDs or processor ID ranges (for example, \fB4,5,6\fR or \fB4,6-8\fR).
.RE

.sp
.ne 2
.na
\fB\fB-C\fR \fIprocessor_set_id\fR\fR
.ad
.sp .6
.RS 4n
Displays data for the CPUs in the processor set specified by
\fIprocessor_set_id\fR.
.sp
\fBintrstat\fR modifies its output to always reflect the CPUs in the specified
processor set. If a CPU is added to the set, \fBintrstat\fR modifies its output
to include the added CPU. If a CPU is removed from the set, \fBintrstat\fR
modifies its output to exclude the removed CPU. At most one processor set can
be specified.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR \fBu\fR | \fBd\fR\fR
.ad
.sp .6
.RS 4n
Display a time stamp.
.sp
Specify \fBu\fR for a printed representation of the internal representation of
time. See \fBtime\fR(2). Specify \fBd\fR for standard date format. See
\fBdate\fR(1).
.RE

.sp
.ne 2
.na
\fB\fB-x\fR \fIopt\fR[=\fIval\fR]\fR
.ad
.sp .6
.RS 4n
Enable or modify a DTrace runtime option or D compiler option. The list of
options is found in the \fIDynamic Tracing Guide\fR. A boolean option
is enabled by specifying its name. Options with values are set by separating
the option name and value with an equal sign (\fB=\fR)
.RE

.SH OPERANDS
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIcount\fR\fR
.ad
.sp .6
.RS 4n
Indicates the number of intervals to execute before exiting.
.RE

.sp
.ne 2
.na
\fB\fIinterval\fR\fR
.ad
.sp .6
.RS 4n
Indicates the number of seconds to be executed before exiting.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBintrstat\fR Without Options
.sp
.LP
Without options, \fBintrstat\fR displays a table of trap types and CPUs. At
most, four columns can fit in the default terminal width. If there are more
than four CPUs, multiple tables are displayed.

.sp
.LP
The following example runs \fBintrstat\fR on a uniprocessor Intel IA/32-based
laptop:

.sp
.in +2
.nf
example# intrstat
               device |      cpu0 %tim
     -----------------+---------------
                ata#0 |       166  0.4
                ata#1 |         0  0.0
          audioi810#0 |         6  0.0
              i8042#0 |       281  0.7
               iprb#0 |         6  0.0
               uhci#1 |         6  0.0
               uhci#2 |         6  0.0

               device |      cpu0 %tim
     -----------------+---------------
                ata#0 |       161  0.5
                ata#1 |         0  0.0
          audioi810#0 |         6  0.0
              i8042#0 |       303  0.6
               iprb#0 |         6  0.0
               uhci#1 |         6  0.0
               uhci#2 |         6  0.0
     ...
.fi
.in -2
.sp

.SH ATTRIBUTES
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	See below.
.TE

.sp
.LP
The command-line syntax is Evolving. The human-readable output is Unstable.
.SH SEE ALSO
.LP
.BR Intro (4),
.BR attributes (7),
.BR dtrace (8),
.BR trapstat (8),
.BR ddi_driver_name (9F)
.sp
.LP
\fIDynamic Tracing Guide\fR:
.sp
.LP
https://illumos.org/books/dtrace/
